home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 501-525 / disk_502 / returncode / returncode.doc < prev    next >
Text File  |  1992-05-06  |  7KB  |  162 lines
  1. LogRC and SetRC - tiny utilities
  2.                              April 17, 1991   Jim Butterfield
  3.  
  4. (LogRC and SetRC will run on all Amiga systems, including
  5. 2.0; but LogRC will not be useful on systems prior to 1.3,
  6. since the ENV: environment was not implemented before then).
  7.  
  8. Every CLI program leaves a Return Code - a number which says
  9. how things went.  (Workbench driven programs do, too, but I'm
  10. not sure if the Return Code is used for anything).
  11.  
  12. A Return Code of 0 means:  fine, things went OK.
  13. A Return Code of 5 means:  warning!  some problem was seen,
  14.     but it didn't stop the program run.
  15. A Return Code of 10 means:  error!  the program run was
  16.     impeded, but the program did struggle through.
  17. A Return Code of 20 means:  fail!  the program couldn't run.
  18.  
  19. You'll find all this in the AmigaDOS User's Manual and elsewhere,
  20. under IF and a bit more under FAILAT.  The Return Code is mostly
  21. of use with script files:  IF can test for levels such as
  22. WARN or ERROR, and FAILAT can decide that a script should give up
  23. if it sees a specified Return Code level exceeded.
  24.  
  25. Chances are, you know all that.  So why LogRC?
  26.  
  27. LogRC
  28. -----
  29.  
  30. Here's the beef:  the IF statement can test the Return Code if it
  31. wishes; but it also CHANGES that value.  IF is a program, too, and
  32. it leaves its own Return Code.  It doesn't HAVE to .. it could be
  33. written to "pass through" the previous value.  But .. no such luck.
  34. One IF test, and the value is lost forever.  (ELSE and ENDIF too).
  35.  
  36. So a little (or big) program might try its best to use a single
  37. number to tell the script about how things went .. and the script
  38. has ONE SHOT at seeing the number.  It could use IF ERROR... but
  39. once that's done, no point in trying IF WARN or IF FAIL.. the
  40. Return Code has been lost and can't be tested again.
  41.  
  42. Should this be reported as a bug to be fixed?  IF, ELSE, and ENDIF
  43. could be changed to "pass through" the Return Code, unchanged.
  44. LogRC and SetRC do that.  Answer:  probably not.  IF and
  45. company have worked that way since forever, and changing 'em now
  46. might cause existing scripts to misfire.  And the quick fix would
  47. not please everyone .. it would be followed by requests to make
  48. nested IF sections work properly with something akin to a "Return
  49. Code stack" .. and that's just the start.
  50.  
  51. Instead, I thought I'd write an itty bitty program called LogRC
  52. which would put the current Return Code into the environment
  53. area.  If you're working in CLI/Shell number 1, LogRC will put
  54. that value into an environment variable called $Return1.  Your
  55. script may then test it repeatedly with syntax such as:
  56.  
  57.     IF $Return<$$> EQ "WARN" ...
  58.     IF $Return<$$> EQ "ERROR" ...
  59.  
  60. The value in that environment variable won't change until you call
  61. LogRC again.  So test away to your heart's content.
  62.  
  63. Ummm .. both LogRC and SetRC are coded as "pure" programs.
  64. Do you care?  The BIG one is under 300 bytes long; conserving
  65. RAM usage may not be your main mania in this case.
  66.  
  67. DOS 2.0 does give you an alternative.  The Return Code (RC) becomes
  68. available as a local variable, $RC, and Result2 as $Result2.
  69. Again, you have ONE SHOT to grab one of these, using a command
  70. such as SET MyRC $RC.  You grab one, you lose the other.
  71.  
  72. About Return Code Levels.
  73. ----- ------ ---- ------
  74.  
  75. Environment variable $RETURN<$$> will contain a string value, a
  76. word such as OK or WARN or FAIL.  You can read it by commanding
  77. "GetEnv Return1".  You can also test with IF as indicated above.
  78.  
  79. A level of 0 translates to string "OK" in the environment variable.
  80. A level of 5 to 9 becomes "WARN"; 10 to 19 shows as "ERROR"; and
  81. 20 and over, "FAIL".  Levels 1 to 4 are not serious enough to be
  82. even a WARN, but they are not zero, so they must be trying to tell
  83. you something.  I've called them MINOR for "minor glitch".
  84.  
  85. Although LogRC is intended for use mostly in scripts, you can
  86. command LOGRC followed by GETENV RETURN1 (use the appropriate
  87. CLI/Shell number).  This will allow you to see results of a program
  88. even when not running a script.  (Or use SetRC, below).
  89.  
  90. A negative Return Code CAN be signalled by a program.  More on this
  91. in SetRC docs, following.  But .. as far as I can tell, the
  92. system throws these values away, and you'll never see a negative
  93. Return Code.
  94.  
  95. SetRC
  96. -----
  97.  
  98. This program was written to help investigate and test the Return
  99. Code operation, so as to get LogRC into shape.  I found it
  100. interesting and useful in its own right.
  101.  
  102. SETRC <number> will set the Return Code to the number supplied.
  103. The number should be supplied in decimal notation; negative numbers
  104. should be prefixed with a minus sign.  SETRC followed by nothing
  105. does NOT set the Return Code; instead, it causes the current
  106. Return Code to be printed.
  107.  
  108. Thus:
  109.  
  110. SETRC 0
  111. SETRC
  112. SETRC 55
  113. SETRC -1
  114.  
  115. This last gives a curious result.  You may know it already; if not,
  116. try it.
  117.  
  118. The numeric value should be in the range -65536 to +65536, more or
  119. less.  I didn't bother putting in the extra code for longword values.
  120. Values outside that range won't cause failure, but results may not
  121. be what you intended.
  122.  
  123. Here's an oddity that I discovered with SETRC.  Any program
  124. returning a negative value will cause the previous Return Code to
  125. remain unchanged.  The negative value will NOT be logged.  Commodore
  126. docs ask you not to use negative values (well, -1 has a special
  127. purpose which you'll discover if you try it, and maybe other values
  128. will be tagged for specific roles in the future).  But they don't
  129. hurt anything at the moment.
  130.  
  131. GetReturn can be quite handy for testing a script file to see if
  132. the "error coding" works as planned.  Wanna fake a WARN level?
  133. Just slip GETRETURN 5 into your script at the appropriate place,
  134. and you've set it up.  Remember:  GetReturn does NOT use the
  135. ENV: handler, and works on ALL Amigas.
  136.  
  137. Return Values
  138. ------ ------
  139.  
  140. Forgive me for belaboring the obvious, but perhaps some programmers
  141. don't know this:
  142.  
  143. The Return Code is set within a C program by means of RETURN(n) ...
  144. value n becomes the system Return Code.
  145.  
  146. The Return Code is set in Assembler by moving that value to the
  147. D0 register just before terminating the program with RTS.
  148.  
  149. Result2:  Future Feature?
  150. --------  ---------------
  151. A second value is often returned by programs, usually to signal how
  152. Input/Output has behaved.  This is "Result2"; if you see an error
  153. notice on your program, it's probably generated by the Result2 value.
  154. Command WHY also repeats Result2, translating its value into text for
  155. you if command FAULT is available.
  156.  
  157. This set of programs does not reference Result2 at the moment.
  158. It could be added; maybe that's a future project.  Maybe not.
  159.  
  160.                                --Jim Butterfield
  161.  
  162.